home *** CD-ROM | disk | FTP | other *** search
/ MacWorld: Complete Mac Interactive / Macworld Complete Mac Interactive CD)(1994).iso / The Best of BMUG / Utilities / Text and Speech / Alpha.5.76 / Help / Intro < prev    next >
Text File  |  1994-03-08  |  67KB  |  1,828 lines
  1. ==============================================================================
  2. = Copyright © 1990-1994 Pete Keleher. All Rights Reserved
  3. ==============================================================================
  4.  
  5. The Author(s) of this product are in no way liable for any direct or 
  6. indirect damage caused by the product. 
  7.  
  8. You may freely copy and distribute ALPHA, but please bear in mind that 
  9. ALPHA is Shareware. If you decide to keep it, please register your copy by 
  10. sending $25 to the author. Site licences are $200. Source licenses are also 
  11. available, inquire with the author. If you include an internet (or 
  12. Compuserve) address with your registration, I will notify you when new 
  13. versions become available. 
  14.  
  15. E-mail address:     pete@cs.rice.edu
  16. Snail-mail address: Pete Keleher
  17.                     1658 Bonnie Brae #2
  18.                     Houston, TX 77006
  19.  
  20. I am collecting user-written Tcl procs and XTCLs in public/Alpha/contrib on 
  21. cs.rice.edu. If you have written anything that you think may be of general 
  22. interest, please send it to me and I will make it available. 
  23.  
  24. Alpha contains source from main places, but in particular I'm grateful to 
  25. Ray Johnson and Tim Endres for their working on porting TCL to the mac.
  26.  
  27. Thanks to Masatsugu Nagata, Karl J. Smith, Tim Endres, Eric Sink, 
  28. David C. Black, Richard T. Austin, Tom Scavo, and Jerry Fowler. 
  29.  
  30.  
  31. What to do:   USE THE "Sections" MENU IN THIS FILE!. This file contains 
  32. "marks" that let you jump to different sections of this file. Mouse-down 
  33. on the box that says "Sections" and move to the section you need.
  34.  
  35. Alpha is a very powerful, multi-purpose editor that allows any program- 
  36. or user-defined function to be bound to any keystroke, or placed into 
  37. user-defined menus. Only the "File", "Edit", and "Search" menus are 
  38. predefined and immutable. The rest are defined in the startup file 
  39. ("AlphaBits.tcl") or files sourced from inside it. 
  40.  
  41. Alpha uses Dr. Ousterhout's Tool Command Language (Tcl) as an extension 
  42. language. See the "Help" menu for a complete definition of the language. 
  43. Alpha uses a port of Tcl done by Tim Endres for his "Tickle" application, 
  44. and supports many of the same extensions. Many of the functions bound to 
  45. keystrokes, as well as many of the functions in the user-defined menus, are 
  46. written in Tcl. 
  47.  
  48. Callable functions in Alpha come in three different flavors. First, there 
  49. are the basic Alpha editor functions; these are discussed in the section 
  50. entitled "Simple Cmds" below. These functions take no arguments and do 
  51. not return values.
  52.  
  53. Second, there are additional Tcl extensions discussed in the "Alpha Tcl 
  54. Extensions" help file (look in the "Help" menu). Most of these functions 
  55. either take arguments or return values. 
  56.  
  57. Finally, there are the Tcl functions defined with "proc". Most of Alpha's 
  58. predefined functions are in "procs.tcl", some are in "shell.tcl". 
  59.  
  60. The only way to get to know the editor and the language is to try different 
  61. things out. Play around. Choose "Misc:List Bindings" to get a listing of 
  62. all the current keystoke bindings. Look in "procs.tcl" for definitions of 
  63. the routines. Look in "AlphaBits.tcl" for definitions of the last six 
  64. menus. And finally, please feel free to send suggestions/"feature" 
  65. reports/questions to me at pete@cs.rice.edu. I am not able to answer US 
  66. postal mail, but if you send it to me I will at least read it. Have fun! 
  67.  
  68.  
  69.  
  70. ==============================================================================
  71. = Reading and Storing Files
  72. ==============================================================================
  73. The primary method of either reading or storing files with Alpha, or any 
  74. other Mac editor, is through the GetFile and PutFile dialogs. However, 
  75. Alpha's dialogs are not exactly like those of other applications. 
  76.  
  77. The GetFile dialog has two additional items: a "Readonly" checkbox and an 
  78. "All Files" checkbox. The first allows you to open a file as read only. 
  79. Files in the readonly state can not be modified, only read. A writable file 
  80. is indicated by a pen icon to the left of the horizontal scrollbar. A 
  81. readonly file is indicated by a pen with a line through it. If you change 
  82. your mind about the file, it's readonly status can be changed by clicking 
  83. on the pen icon. 
  84.  
  85. The second checkbox, "All Files", allows Alpha to open any file rather 
  86. than just those of type 'TEXT'. The type of a file can be determined by 
  87. using the 'll' alias in the Tcl shell.
  88.  
  89.  
  90. The PutFile dialog is used to prompt the user for a new name under which to 
  91. save the contents of a window. This dialog has been enhanced by two popup 
  92. menus: "State" and "Format". "State" allows you to specify how much 
  93. information should be saved in the resource fork of files that you use. If 
  94. the state is set to "MPW", window position, current selection, tab sizes, 
  95. and font information are saved into the resource fork of your application 
  96. every time you open and close it, *even if you don't modify the file*. 
  97. Alpha still manages to coexist with build or make files because saving this 
  98. information does not change the modification date of the file. If the state 
  99. is set to "Think", neither the window position nor the current selection 
  100. are saved. If state is set to "None", no information is saved. The default 
  101. value for saved state can by changed by setting the Alpha variable 
  102. 'savedState' to "mpw", "think", or "none". Note that if a given file 
  103. already has mpw information in it when the file is open, Alpha will always 
  104. update that information when the file is closed. Note also that "marks" 
  105. are always saved in the resource fork whenever a file is saved, 
  106. regardless of the setting of the 'savedState' variable.
  107.  
  108. The "Format" menus allows the way Alpha terminates lines to be changed. 
  109. The Mac uses a carriage return to mark the end of a line, Unix uses a 
  110. linefeed, and IBM uses both (of course). Alpha can read and write any of 
  111. these formats, and can convert between them just by opening a file, 
  112. choosing "Save As", and changing the selection in this menu. Note that if 
  113. you are going to be sharing files with a Unix or IBM machine, you 
  114. probably don't want anything in your resource fork, so you'd probably 
  115. want to set 'savedState' to 'none' in your AlphaBits.tcl file.
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122. ==============================================================================
  123. = The Window
  124. ==============================================================================
  125.  
  126. Alpha's windows have several non-standard features. 
  127.  
  128. First, on the title bar at the left, there are either one or two boxes. If 
  129. there is only one box, the box implements a popup menu of all marks set in 
  130. the file. If there are two boxes, the left box implements a popup menu of 
  131. all functions in the current file (as defined by the 'funcExpr' regular 
  132. expression) and the right box implements the mark menu. These boxes can 
  133. be turned off via the flag 'showMenuHeads' in the "Utils:Flags" submenu. 
  134.  
  135. On the right of the titlebar, there is a running display of the current 
  136. row and column. These boxes can be turned off via the 'showRowCol' flag.
  137.  
  138. All title-bar boxes are turned off when Alpha is using full names for 
  139. window titles.
  140.  
  141. At the bottom of the window, the first box is a status display area. 
  142. Also, "Utils:Execute…" prompts for a Tcl expression in this space. To the 
  143. right of the status area is an icon displaying the readonly status of the 
  144. file. If the icon is just a pen, the file is writable. If the icon is a 
  145. pen w/ a bar through it, the file is not writable. The readonly status of 
  146. the window can be toggled by clicking on the icon.
  147.  
  148. To the right of the readonly icon area is the mode display area. Alpha 
  149. allows you to have any number of different modes, w/ different bindings 
  150. and behavior in each. The mode display not only shows the current mode, 
  151. but also implements a popup menu allowing you to change the current mode 
  152. for the window.
  153.  
  154. ==============================================================================
  155. = Marks
  156. ==============================================================================
  157.  
  158.  
  159. Alpha allows the user to use "marks" to remember positions in files. Marks 
  160. "float". That is, if a mark is initially at position 312 and then five 
  161. characters are inserted at location 297, the mark's new value will be 317. 
  162. Alpha uses three different types of marks. 
  163.  
  164. The first is generically referred to as "the mark". The mark is set to the 
  165. current insertion point by the command 'setMark' (control-space by 
  166. default). The position in the file indicated by the blinking cursor is 
  167. referred to as the current insertion point. Many commands (such as "cut" 
  168. and "copy") can operate either on the currently selected (hilighted) text, 
  169. or the text between the current insertion point and "the mark". For 
  170. example, if you move the cursor to the beginning of the work "allybaba", 
  171. hit command-space (the status bar should say "Mark set"), move to the end 
  172. of the word and hit option-w (the status bar should say "Region copied"), 
  173. the effect is the same as if you had used the mouse to select the text and 
  174. then selected the "Copy" command from the "Edit" menu.
  175.  
  176. The second type of mark are the permanent marks. Permanent marks are set, 
  177. removed, and moved-to through the three corresponding menu items in the 
  178. "Search" menu. Permanent marks differ from the generic mark in that they 
  179. have names, there can be any number of them, and they are saved in the 
  180. resource fork if the file is subsequently saved.
  181.  
  182. The third type of mark is the temporary mark. Like permanent marks, 
  183. temporary marks can be named and there can be any number of them. Unlike 
  184. permanent marks, temporary marks do not "dirty" the file, and they aren't 
  185. saved. So far, temporary marks are used exclusively to implement higher 
  186. order functions in TCL procedures. In the 5.0 release, temporary marks are 
  187. used to implement a "mark stack" and a for loop template.
  188.  
  189. At the time a file is saved, the marks for that file are stored into the 
  190. file's resource fork in an order determined by the variable 
  191. 'markSorting'. The choices are either 0 (no sorting), 1 (sort by file 
  192. position), or 2 (sort alphabetically).
  193.  
  194.  
  195. ==============================================================================
  196. = The Mark Stack
  197. ==============================================================================
  198.  
  199. The mark stack is a last-in-first-out (LIFO) stack of temporary marks 
  200. managed by the TCL procedures 'pushMark' and 'popMark'. 'pushMark' creates 
  201. a new temporary mark of the current insertion point and adds it on to the 
  202. top of the stack. 'popMark' removes the top mark from the stack and goes 
  203. toit. A typical use of the mark stack is a 'pushMark' at the current 
  204. position, go look somewhere else in the file, and then 'popMark' to get 
  205. back to where you were. However, the stack is recursive, so there can be 
  206. any number of 'pushMarks' before the marks start to be popped back off the 
  207. stack.
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232. ==============================================================================
  233. = Templates
  234. ==============================================================================
  235.  
  236. Temporary marks can also be used to with language construct templates. The 
  237. file "template.tcl" contains an example implementing a template for C's 
  238. 'for' command. Depressing control-i will insert a template for the "for" 
  239. command into the current window. Five temporary marks are defined in the 
  240. for structure, three inside the parenthesis, one where the "for" body text 
  241. will be inserted, and one after outside the for body entirely. Depressing 
  242. control-shift-i moves the cursor to the next of the five temporary marks 
  243. allowing quick entry of the entire command.
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269. ==============================================================================
  270. = The Tool Command Language (TCL)
  271. ==============================================================================
  272.  
  273. See the Tcl manual page under the 'Help' menu for a complete description of 
  274. Tcl, the Tcl shell, and it's commands. Each of the Tcl commands and several 
  275. sections have a mark defined, so you can use the "Mark" titlebar menu to 
  276. navigate through the manual page. If you define the file
  277. ":Tcl:UserCode:userStartup.tcl", Alpha will load it at startup.
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307. ==============================================================================
  308. = Key Bindings
  309. ==============================================================================
  310.  
  311.  
  312. Any TCL command can be bound to any single keystroke. One way to bind a 
  313. function is with a statement such as:
  314.   
  315.       bind 'c' <modifier string> funcName [<mode>]
  316.           
  317. where c is a character, <modifier string> is an optional string containing 
  318. one or more of:
  319.  
  320.       c   - command modifier
  321.       o   - option modifier
  322.       s   - shift modifier
  323.       z   - control modifier
  324.       e   - escape modifier      
  325.  
  326. Additionally, the modifier string can contain a capital letter specifying 
  327. that the binding is only activated if preceded by control and the lowercase 
  328. version of that letter. This feature allows multiple-key combinations ala 
  329. Emacs. The following line binds cmd-shift-f to the function 'forwardChar': 
  330.  
  331.  bind 'f' <cs> forwardChar 
  332.  
  333. The next line would bind the same function to C-x C-f: 
  334.  
  335.  bind 'f' <cX> forwardChar 
  336.  
  337. 'mode' is an optional parameter that specifies, when present, that the 
  338. binding is only active in a given mode, where the current mode is the 
  339. parameter to the last call of 'displayMode' (look in "procs.tcl"). Note 
  340. that given a general binding (no mode specification) and a binding specific 
  341. to the current mode, the last binding to have been created is the one found 
  342. first. 
  343.  
  344. Additionally, most keyboards have keypads and/or Function Keys. These 
  345. keys can be bound using case-insensitive numeric labels using the same 
  346. bind command as above, with the label replacing the character. For 
  347. example, to bind F1 to function 'funcName', the following would work:
  348.  
  349.     bind F1 funcName
  350.  
  351. As above, the binding can include a modifier string. The following labels 
  352. are defined for US keyboards:
  353.  
  354.   Esc F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 Help Home Pgup Del 
  355.   End Pgdn Left Right Up Down Clear Kpad0 Kpad1 Kpad2 Kpad3 Kpad4 Kpad5
  356.   Kpad6 Kpad7 Kpad8 Kpad9 Kpad= Kpad/ Kpad* Kpad- Kpad+ Enter Kpad.
  357.  
  358. The function 'listBindings' will list all of the bindings currently in 
  359. effect in a format suitable for re-loading.
  360.  
  361. The above labels may not be sufficient for all keyboards (attention 
  362. international users). If a hex number is used instead of a character inside 
  363. the single quotes, the binding is done to key codes instead of ascii 
  364. values. The following is a key code version of the same binding: 
  365.  
  366.       bind 0x03 <cs> forwardChar
  367.  
  368. The key code for any given key can be obtained by using the 'keyCode' 
  369. function. 
  370.  
  371. Also, there is an alternate form that allows the specification of an 
  372. ascii code directly:
  373.  
  374.     ascii 0x20 <z> setMark
  375.     
  376. Binds control-space to 'setMark'.
  377.  
  378. Note that menu item command equivalents take precedence over bindings, 
  379. and that the 'bind' command does not affect the command equivalents 
  380. displayed in the menus. Command equivalents can only be changed by using
  381. an external tool like 'ResEdit'. Also note that key code bindings take 
  382. precedence over ascii bindings. 
  383.  
  384.  
  385. ==============================================================================
  386. = Menus
  387. ==============================================================================
  388.  
  389. Alpha's menus are completely reconfigurable. Some of the menu items are 
  390. internal alpha commands, while others are Tcl procs defined in one of the 
  391. files of the "Tcl" subdirectory. Most of these procs are defined in 
  392. "procs.tcl". The following is an explanation of the default menus. The 
  393. explanations of items that are defined as Tcl procs are implemented by the 
  394. Tcl proc specified by "(proc <name>)", and can be found in one of the .tcl 
  395. files. All others are internal functions. 
  396.  
  397. File
  398.     New                      New file.
  399.     Open…                   Open file.
  400.     Close                   Close file.
  401.     Save                       Save file.
  402.     SaveAs…                   Prompt for name to same file under.
  403.     Revert                   Revert to last saved version, throw away undo history. 
  404.     Shell                   Start up command-line shell that interprets Tcl commands. The 
  405.                             shell has a few csh-type features, such as 'ls', 'rm', etc. 
  406.                             commands, as well as file completion with the TAB key. 
  407.     Page Setup…               Set print options.
  408.     Print…                  Print file.
  409.     Quit                       Quit Alpha.
  410.  
  411. Edit
  412.     Undo                    Undo. 
  413.     Redo                    Redo. 
  414.     Load Window
  415.     Load Selection            Execute either the window or the selection as Tcl source. 
  416.     Cut                        Cut selection to scrap.
  417.     Copy                    Copy selection to scrap.
  418.     Paste                    Paste from scrap.
  419.     Yank                    Paste last deleted text. Concatenates together consecutive, 
  420.                             adjoining deletions.
  421.     Select All                Select entire file.
  422.     Clear                    Delete selection.
  423.     Shift Left                Shift selection left one tab.
  424.     Shift Right                Shift selection right one tab.
  425.     Balance                    Select text out to the next set of matching braces.
  426.     Hilite                    Select text between current insertion and the generic "mark". 
  427.                             Or, if there is already a selection, unselect the text, place
  428.                             the insertion at the beginning of the unselection, and place the 
  429.                             "mark" at the end of the unselection. The function 
  430.                             'exchangePointAndMark' (by default mapped to the "5" on the keypad 
  431.                             and control-x,control-x) exchanges the character positions of the 
  432.                             insertion and the "mark". 
  433.     
  434. Search
  435.     Find..                    Present a search dialog.
  436.     Repeat Search Forward    Search forward again w/ same settings.
  437.     Repeat Search Backward    Search backward again w/ same settings.
  438.     Find in Next File        Restart multiple-file search in next file after 
  439.                             stopping at a match.
  440.     Enter Selection            Make the current selection the text to be searched for.
  441.     Replace                    Replace the selection.
  442.     Replace and Find Again.    Replace the selection and search again forward.
  443.     Replace All                Replace all of occurances of the search string in the rest 
  444.                             of the file.
  445.     Goto Line…                Go to specific line.
  446.     Set Mark…                Set permanent named mark.
  447.     Goto Mark…                Goto permanent named mark.
  448.     Remove Mark…            Remove permanent named mark.
  449.     
  450. Utils
  451.     Short Menus                Remove some menus and menu items (proc shortMenus).
  452.     Flags                    A submenu of Tcl flags to be turned on and off. Look under 
  453.                             "Variables" for explanations of individual flags (proc editFlag).
  454.     Vars                    Same as Flags, except these variables may be arbitrary integers 
  455.                             or strings (proc editVar).
  456.     File Utils
  457.         Insert File…        Insert the text of another file.
  458.         Remove File…        Remove a file.
  459.         File Info…            Display/edit info about a file.
  460.         Word Count            Count lines, words, chars in window (proc wordCount).
  461.     FileSets                Submenu allowing the "current" fileset to be specified. A 
  462.                             fileset is a list of files used by various Alpha functions.
  463.                             (proc changeFileSet).
  464.     Create File Set…        Create a fileset on the fly. (proc addFileSet)
  465.     Dump File Set…            Dump a Tcl representation of a fileset into the current 
  466.                             buffer.
  467.     Find Tag                Find a "tag" created using the "Create Tag File". Tags can 
  468.                             be used to automatically track the locations of all functions in a 
  469.                             "C" program, for example, so that you can jump to a function, 
  470.                             regardless of location, merely by using "Find Tag".
  471.     Create Tag File            Creates a tag file of the current fileset, stores in 
  472.                             file named by 'tagFile' variable.
  473.     Execute                    Quick way to execute a Tcl command. TAB implements command
  474.                             completion. 
  475.     Push Mark                Push onto a Last-In-First-Out stack of temporary marks (proc 
  476.                             pushMark).
  477.     Pop Mark                Pop from LIFO stack (proc popMark).
  478.     Prev Func                Use the value of 'funcExpr' to search for the previous 
  479.                             function definition (proc prevFunc).
  480.     Next Func                Use the value of 'funcExpr' to search for the next
  481.                             function definition (proc nextFunc).
  482.     Start Keyboard Macro    Start recording actions for later replay.
  483.     End Keyboard Macro        Stop recording actions.
  484.     Execute Keyboard Macro    Re-execute recorded actions.
  485.     Dump keyboard Macro…    Name and insert a Tcl proc implementing the last 
  486.                             recorded sequence of actions.
  487.     
  488. Misc
  489.     Paste Pop                Call this function consecutively after pasting and get 
  490.                             previous clipboard contents. 
  491.     List Bindings            Create a new file containing all current key bindings.
  492.     Describe Binding…        Wait for a keystroke, then display that keystroke's binding.
  493.     Insert Path Name…        Prompt for a directory and insert result.
  494.     Set Font Tabs…            Change font and/or tabs for current file.
  495.     Copy Named Clipboard…    Copy selection to user-named clipboard.
  496.     Cut Named Clipboard…    Cut selection to user-named clipboard.
  497.     Paste Named Clipboard…    Paste from user-named clipboard.
  498.     Ascii Etc
  499.         Key Code…            Wait for key press and insert keycode and modifier string 
  500.                             suitable for key binding.
  501.         Key Ascii…            Same as above, but use ascii form.
  502.         Get Ascii…            Display ascii code for char to right of insertion.
  503.         Insert Ascii…        Prompt for ascii code and insert character.
  504.     Switch To                Bring other apps to front.
  505.     ToolServer Shell        Start a window that sends 'DOSC' events to Apple's 
  506.                             toolserver. 
  507.     Load Electric Alias        Load David Black's 'electricAlias' package. See the 
  508.                             "Help" menu for more details (proc loadElectricAlias).
  509.     
  510.  
  511. Convert
  512.     Toggle Scrollbar        Toggle the horizontal scrollbar on the frontmost 
  513.                             window. The scrollbar can be enabled/disabled on subsequent 
  514.                             variables by changing the value of the 'horScrollBar' flag.
  515.     Fill Region                "Fill" selection subject to 'leftFillColumn' and 
  516.                             'fillColumn', (proc fillRegion).
  517.     Fill Paragraph            "Fill" paragraph that contains the insertion (proc 
  518.                             fillParagraph).
  519.     Wrap Region                Break lines longer than 'fillColumn' in selection 
  520.                             (proc wrapRegion).
  521.     Wrap Paragraph            Break lines longer than 'fillColumn' in paragraph 
  522.                             containing insertion pt (proc wrapParagraph).
  523.     Sort Lines                Sort selected lines (proc sortLines).
  524.     Matching Lines            Grab all lines from current position on that match a 
  525.                             regular expression and dump in new buffer (proc matchingLines). 
  526.     Zap Invisibles            Delete all chars in file w/ ASCII code < 32, except for 
  527.                             LF, TAB and CR.
  528.     Tabs To Spaces            Convert tabs to space runs.
  529.     Spaces To Tabs            Convert space runs to tabs.
  530.     Strings
  531.         Insert Prefix        Prepend string 'prefixString' to every line in selection 
  532.                             (proc insertPrefix).
  533.         Insert Suffix        Append string 'suffixString' to every line in selection 
  534.                             (proc insertSuffix).
  535.         Remove Prefix        Remove prefix string from lines in selection 
  536.                             (proc removePrefix). 
  537.         Remove Suffix        Remove suffix string from lines in selection 
  538.                             (proc removeSuffix). 
  539.         Set Prefix…            Change prefix string (proc setPrefix).
  540.         Set Suffix…            Change suffix string (proc setSuffix).
  541.     Colors
  542.         Fore Color…            Set foreground color.
  543.         Back Color…            Set background color.
  544.         Dump Colors            Dump tcl script to set current colors.
  545.     Paragraph To Line        Convert paragraph to single long line, useful for 
  546.                             exporting text to word processors (proc paragraphToLine).
  547.     Line To Paragraph        Convert long line to paragraph, useful for importing 
  548.                             text from word processors (proc lineToParagraph).
  549.                             
  550. Help
  551.     Editor help files (proc helpMenu).
  552.     
  553. Wins
  554.     Arrange                    Rearrange open windows.
  555.     Zoom                    Zoom windows in and out.
  556.     Iconify                    Replace window w/ small icon (proc iconify).
  557.     Next Window                Select next window (proc nextWindow).
  558.     Swap With Next            Swap topmost two windows (proc swapWithNext).
  559.     Choose A Window            Choose window to select from list (proc chooseAWindow).
  560.     Prev Window                Select previous window (proc prevWindow).
  561.     Close All                Close all windows (proc closeAll).
  562.     Save All                Save all dirty windows (proc saveAll).
  563.  
  564.     
  565.     
  566. ==============================================================================
  567. = User-Defined Menus
  568. ==============================================================================
  569.  
  570. All of Alpha's menus are defined in the initialization files that Alpha 
  571. loads on startup.  They can be altered or discarded at well.  Alpha's menu 
  572. commands allow the the user to build custom menus which contain names of 
  573. functions, macros, or arbitary TCL commands that just HAVE to be in the 
  574. menus, as opposed to being merely callable through the bindings.  The 
  575. syntax is dead simple.  Menus can be nested, allowing heirachical menus to 
  576. be defined.  See the 'AlphaBits.tcl' file for examples (only the first 
  577. three Alpha menus are hard-coded into the Application, the others are set 
  578. up through the AlphaBits file).  The following meta characters can be 
  579. embedded in the strings:
  580.  
  581.    Meta-character     Usage
  582.    --------------     -----
  583.  
  584.     ; or Return       Separates multiple items.
  585.     ^                 Followed by an icon number, adds 
  586.                       that icon to the item.
  587.     !                 Followed by a character, marks the
  588.                       item with that character.
  589.     <                 Followed by B, I, U, O, or S, sets 
  590.                       the character style of the item.
  591.     /                 Followed by a character, sets up
  592.                       a keyboard equivalent.
  593.     (                 Disables the item.
  594.  
  595. The menu creation syntax is :
  596.  
  597.     menu <-n name> <-i num> [-p procName] [-m] "Tcl list of items"
  598.  
  599. Where the arguments have the followings meanings:
  600.   '-i <num>'    Resource id of icon suite to use for menu title.
  601.   '-n <name>'    Name of menu.
  602.   '-m'            No menu form. If not supplied, each menu item is split into 
  603.                   words at each capitalized letter.
  604.   '-p <pname>'     Rather that having alpha call a Tcl proc named by the menu 
  605.                   item's text, this option tells Alpha to call the tcl proc named by 
  606.                   'pname' with two arguments: the menu name, and the text of the menu 
  607.                   item chosen.
  608.  
  609. Once the menus are created, they can be inserted and  deleted from the 
  610. menu bar by the syntax:
  611.  
  612.    insertMenu "name"
  613.    deleteMenu "name"
  614.  
  615. as well as through macros.
  616.  
  617.  
  618. As alluded to above, Alpha attempts to make procedure names readable in the 
  619. menus by separating words at any capitalized letter. For example, 
  620. 'findFile' becomes "Find File". This function is turned off by the '-m' 
  621. option. 
  622.  
  623. Menu items can be enabled and disabled through the TCL command 
  624. 'enableMenuItem'. Menu items checkmarks can be turned on and off via 
  625. 'markMenuItem'. Menu items can be appended via 'addMenuItem' and deleted 
  626. via 'deleteMenuItem'. See the "Alpha Tcl Extensions" help file for syntax. 
  627.  
  628. If an ellipsis ('…') is the last character in a menu item, it is stripped 
  629. off before searching for the function corresponding to the chosen item. 
  630.  
  631.  
  632. #================================================================================
  633. # Just for the heck of it, the following is a script that I put in my 
  634. # userStartup.tcl file. It creates a menu for all the .tex files in my 
  635. # thesis directory, minus the dirname and .tex extension.
  636. #
  637. set THESIS "Internal:Textures:thesis"
  638. proc thesisMenuProc {menu item} {
  639.     global THESIS
  640.     edit -r -m $THESIS:$item.tex
  641. }
  642.  
  643. set files ""
  644. foreach f [glob $THESIS:*.tex] {
  645.     lappend files [file rootname [file tail $f]]
  646. }
  647. menu -n Thesis -m -p thesisMenuProc $files
  648. unset files
  649. #================================================================================
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659. ==============================================================================
  660. = Event Hooks
  661. ==============================================================================
  662.  
  663.  
  664. Alpha calls the TCL procs "openHook", "saveHook", "saveasHook", "closeHook", 
  665. "activateHook", "deactivateHook", "suspendHook", and "resumeHook" when the 
  666. corresponding events occur. With the exception of "saveasHook", the proc 
  667. are all called with the complete pathname as the sole argument. 
  668. "saveasHook" is called with the old pathname as the first argument and the 
  669. new pathname as the second argument. Default implementations for these 
  670. commands are in the file 'proc.tcl'. These commands can be modified to 
  671. perform arbitrary commands, including saving of files, backups, 
  672. implementations of per-window variables, etc. 
  673.  
  674.  
  675.  
  676.  
  677.  
  678.  
  679.  
  680.  
  681.  
  682.  
  683.  
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.  
  694.  
  695.  
  696.  
  697.  
  698.  
  699.  
  700. ==============================================================================
  701. = Searching
  702. ==============================================================================
  703.  
  704.  
  705. ALPHA has a full repertoire of searching commands.  The 'find' command 
  706. brings up a dialog allowing the search and replacement text to be 
  707. specified.  The dialog also allows 'Forward', 'Ignore Case', 'Reg Expr', 
  708. and 'Word Match' options to be set.  These options can be toggled via the 
  709. keyboard by clover-<first letter of option>.  For example, clover-w toggles 
  710. the 'Word Match' option.
  711.  
  712. The 'Mult Files' option tells Alpha to search through all files in a given 
  713. file set.  Filesets can be specified in 'procs.tcl' (see the section on 
  714. filesets) or on the fly, via the "Add Fileset…" item of the "Utils" menu. 
  715. Filesets can be chosen via the popup fileset menu.
  716.  
  717. In addition to the current filesets, the fileset menu has an entry called 
  718. "Directory Scan". Selecting this menu item enables the "Scan Options" 
  719. button. This button, in turn, allows the specification of a directory and 
  720. a file pattern to be searched instead of a fileset. To set the directory, 
  721. hit the "Dir:" button. The pattern is used to select files of the 
  722. selected directory. The '*' wildcard character can be used to replace any 
  723. sequence of characters. For example, the pattern '*.c' will select any 
  724. file ending with ".c". If this doesn't work, be sure that you executed 
  725. all of the following steps:
  726.         1) select "Directory Scan" in the popup menu of the find dialog
  727.         2) Hit the "Scan Options" button.
  728.         3) Select a directory via the "Dir:" button.
  729.  
  730. And finally, Alpha allows a library of useful search and replace texts to 
  731. be defined as a tcl list of lists (each sublist containing a name, search 
  732. text, and replacement text). This list, the 'patternLibrary' variable 
  733. defined at the end of 'procs.tcl', is used to create a popup menu in the 
  734. find dialog allowing these patterns to be easily entered.
  735.  
  736. Once the text and options have been set, the 'Search' menu contains several 
  737. commands for repeated searching, replacing, etc. 
  738.  
  739.  
  740. ==============================================================================
  741. = Regular Expressions
  742. ==============================================================================
  743.  
  744. If the variable 'regExpr' is true, the search functions interpret the 
  745. search text as regular expressions, which have the following elements:
  746.  
  747.  c        literal char.
  748.  ^        beginning of line.
  749.  $        end of line.
  750.  .        any character except carriage return.
  751.  [...]    character class, can use ranges such as '0-9'.
  752.           inside classes. Matches one character of the 
  753.           enclosed choices. Ex: '[ac0-2]' matches 'a', 
  754.           'c', '0', '1', or '2'.
  755.  [^...]   negated character class, matches anything but
  756.           the enclosed characters. ']' can be included
  757.           by putting it immediately after the '^'.
  758.  \t       tab.
  759.  \r       carriage return or line break.
  760.  *        zero or more occurrences of the previous
  761.           pattern. Ex: 'ab*' matches 'a', 'ab', 'abb',
  762.           'abbb' etc.
  763.  +        one or more occurrences of the previous 
  764.           pattern. 
  765.  ?        zero or one occurrences of the previous 
  766.           pattern. Ex: 'ab?' matches 'a' or 'ab'.
  767.  a|b      matches either a or b. If enclosed in
  768.           parenthesis, the extent of the alternated
  769.           expressions is limited. Ex: (pete|bob) 
  770.           matches either 'pete' or 'bob'.
  771.  (...)    The interior elements are grouped together. 
  772.  
  773. Regular expressions constructed from the above elements can be 
  774. concatenated to create larger expressions. 
  775.  
  776. The parenthesis also define substrings of the total matched string that 
  777. can be used either later during substitution. The substring delimited by 
  778. the pair of parenthesis that includes the nth left paren is denoted \n, 
  779. where n is 1, 2, .... 9.  '\0' and '&' both refer to the matched text.
  780.  
  781. EXAMPLE: 
  782. The following regular expression will match either 'aabox' or 'bbbox':
  783.  
  784.               (aa|bb)box
  785.  
  786. Regular expressions can be very difficult to master, but they the 
  787. following section shows how useful they can be.
  788.  
  789. The text used in searches and replaces can be accessed through the alpha 
  790. variables 'searchStr' and 'replaceStr'.
  791.  
  792.  
  793. ==============================================================================
  794. = Incremental Searches
  795. ==============================================================================
  796.  
  797. Emacs users will be happy that both forward and backward incremental 
  798. searches are implemented. Incremental searches bypass the normal search 
  799. dialog and search for the current text after each keystroke. The result is 
  800. often much faster and less intrusive. Executing either while an incremental 
  801. search is in progress causes the search to proceed to the next instance of 
  802. the current text. Incremental search mode is exited when any other command 
  803. (executed through the menus or through bindings that include at least one of 
  804. the control key and the option key) is executed, or when the escape or 
  805. delete key is used. 
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831. ==============================================================================
  832. = 'C' Tags
  833. ==============================================================================
  834.  
  835.  
  836. ALPHA supports the use of tags to find declarations of functions. When 
  837. searching for a tag, ALPHA looks for the tag file specified by the 
  838. "tagFile" string variable. ALPHA's tag generating routines use the regular 
  839. expression in the string variable "funcExpr" to look for function 
  840. declarations. In other words, we don't parse the text. If you declare your 
  841. functions differently, you can change " funcExpr" to suit your own style. 
  842. Alpha currently uses the following regular expression to find C function 
  843. declarations:
  844.  
  845.               ^[^ \t#\r/@][^\r]*\([^\r]*\)$
  846.  
  847. (NOTE: the above expressions won't pick up many C++ method definitions. To 
  848. pick them up, add a question mark '?' after the last right parenthesis.) 
  849. Although complicated, this expression makes sense if you slowly wade 
  850. through it. The string that we are looking for must take up an entire 
  851. line. It must begin with a character other than '\t', '#', '\r', '/', ' ', 
  852. or '@'. There must be a set of parenthesis.   
  853.  
  854. Note that not only can you customize this to your style of 'C' 
  855. declarations, you could also use it to generate tags for other languages. 
  856. The only thing you need to bear in mind is that the tag routines use the 
  857. complete word previous to the first '(' in the selected line as the 
  858. function's name. If there is no '(' in the selected line, the last word in 
  859. the line is used. Therefore, Pascal procedures w/ or w/o parameters can be 
  860. identified.
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868. ================================================================================
  869. = Backups
  870. ================================================================================
  871. If the 'backup' variable is set in userStartup.tcl, or from the 
  872. Utils:Flags menu, Alpha backs up each file before saving new 
  873. modifications. By default, the backup file is in the same directory, and 
  874. its name is formed by suffixing a tilde to the name of the saved file. 
  875. Backups are actually performed in the 'saveHook' proc (see above), in the 
  876. file procs.tcl. The Tcl variables 'backDir' and 'backExtension' can be 
  877. used to modify this behavior.
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905. ==============================================================================
  906. = "Fill" Routines
  907. ==============================================================================
  908.  
  909.  
  910. The "fill" and "wrap" routines reformat text to specified line lengths. 
  911. This is useful in two case. First, word processors such as Microsoft Word 
  912. only insert carriage returns at the end of paragraphs. Secondly, while 
  913. typing and inserting text into pre-existing paragraphs, the line lengths 
  914. become unequal. 
  915.  
  916. The "wrap" routine handles word processor documents quickly by merely 
  917. inserting carriage returns as necessary to ensure all lines in the 
  918. selected region are shorter than specified by the variable 'fillColumn'. 
  919. Alpha asks the user if wrapping should be done whenever the user opens 
  920. files that have lines longer than 'paraColumn' characters.
  921.  
  922. The TCL routines 'fillRegion' and 'fillParagraph' go further. Not only do 
  923. they break lines, but they also coalesce lines to eliminate short lines. 
  924. Both routines work by stripping the relevent text of white space, then 
  925. re-inserting white space and carriage returns so that no line extends past 
  926. 'fillColumn' characters in length and begins with 'leftFillColumn' spaces 
  927. characters. Both routines are implemented in the file 'procs.tcl', and 
  928. therefore different definitions of paragraphs can be accomodated by 
  929. modifying the appropriate TCL procedures.
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943. ==============================================================================
  944. = Titlebar Menus
  945. ==============================================================================
  946.  
  947.  
  948. If the value of the variable 'showMenuHeads' is non-zero, every text window 
  949. contains two boxes in the title bar. By default, the first contains 
  950. subboxes entitled "Func" and, "Mark". Depressing the mouse in these boxes 
  951. bring up popup menus (Note, however, that there might only be one subbox, 
  952. see below).
  953.  
  954. The "Func" menu uses the regular expression defined by the string variable 
  955. 'funcExpr' to create a popup menu containing a sorted list of all function 
  956. definitions in the current file. Using regular expressions this way is not 
  957. going to pick up all function definitions if your coding style is very 
  958. different than what Alpha expects. If this is the case, you may need to 
  959. play with the definition for 'funcExpr'.
  960.  
  961. Selecting an item from this menu immediately displays the definition of 
  962. that function. If the 'shift' key is depressed when the menu is created, 
  963. the methods menu is not sorted. The 'sortedIsDefault' var reverses these 
  964. semantics.
  965.  
  966. The "Mark" menu displays a list of all permanent marks in the current 
  967. file. Selecting an item from the menu causes the insertion to be placed at 
  968. the corresponding mark.
  969.  
  970. The behavior of the function menu can be changed dramatically by the user. 
  971. The method-func routine uses 'funcExpr' to locate a line containing a C 
  972. definition, and then another routine extracts the function name. 
  973.  
  974. Finally, by default, the label of the menu is "Func", and for each match 
  975. found, a menu item is created with the text of the last word before the 
  976. first left parenthesis in the match.  For example, if the following is 
  977. matched text:
  978.  
  979.     this is matched text (one (silly))
  980.  
  981. the word 'text' would be inserted into the popup menu as an item.
  982.  
  983. The label of the menu can be changed via the function 'winFuncTitle'.  If 
  984. the second argument of 'winFuncTitle' is a string other than "Func", two 
  985. things happen.  First, the argument is used as the label for the func popup 
  986. box.  Second, Alpha adds a menu item constructed from the text inside the 
  987. 'funcPar'th parenthesized expression in the match, where 'funcPar' is an 
  988. Alpha variable of the same name.  Note that the parenthesis in this case 
  989. are part of the regular expression, the actual text may not have 
  990. parenthesis at all, and probably doesn't.  For more information on this, 
  991. look at the manual page for regular expressions (in the "Help" menu).
  992.  
  993. See the startup files for examples of both methods.
  994.  
  995. If the window is opened through 'edit' or 'fileMenu' and has the '-m' 
  996. option set, the mark menu is relabeled to the value of 'markLabel' and the 
  997. other menu is removed entirely. This is mainly used for help files. 
  998.  
  999. And finally, the system interprets the following characters (see the 
  1000. section describing how to create menus): ';', '^', '!', '<', '/', and 
  1001. '('. These characters will be changed to periods in the titlebar menus. 
  1002.  
  1003. The function menu is limited to 150 items.
  1004.  
  1005.  
  1006. ==============================================================================
  1007. = Word Breaking
  1008. ==============================================================================
  1009.  
  1010. Alpha allows you to redefine it's internal notion of what a word is, 
  1011. through the variables 'wordBreak', and 'wordBreakPreface'. 'wordBreak' is 
  1012. set to a regular expression that defines a word to you. 'wordBreakPreface' 
  1013. should be a regular expression that matches exactly one of any characters 
  1014. that are not in your word definition. 
  1015.  
  1016. For instance, the default definition of 'wordBreak' is '[a-zA-Z0-9_]+'. 
  1017. This matches any contiguous sequence of contiguous alphanumeric 
  1018. characters, plus underscore.
  1019.  
  1020. The default value for wordBreakPreface is '[^a-zA-Z0-9_]', basically just 
  1021. the negation of any any of the characters in your 'wordBreak' definition. 
  1022.  
  1023. The need for both these variables in backward searches can be seen as 
  1024. follows. Suppose your window's text is "hey hello", and the current 
  1025. insertion is between the two 'l's. Now, searching backwards for the above 
  1026. 'wordBreak' definition will take the insertion to between the 'e' and the 
  1027. first 'l', not really where we want to say is the start of the word. By 
  1028. contrast, if we search backwards for 'wordBreak' and 'wordBreakPreface' 
  1029. concatenated together, and then move forward one character after a 
  1030. successful search, we end up right before the 'h' in 'hello', just where 
  1031. we want to be.
  1032.  
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047. ==============================================================================
  1048. = Defining and Using File Sets
  1049. ==============================================================================
  1050.  
  1051. File Sets are lists of files that Alpha uses for multiple-file searches and 
  1052. tag searches, among other things. Typically, a user will set up several 
  1053. different file sets in the AlphaBits.tcl file, perhaps one specifying all 
  1054. the source files in a project, another specifying all the Mac include 
  1055. files, and another specifying all the UNIX include files. When a command 
  1056. using file sets is initiated, Alpha evaluates the command "getCurrFileSet", 
  1057. which returns a list of complete pathnames to search. Some of the lists are 
  1058. set up explicitly (see the 'noGlobNecessary' definition in "procs.tcl"), 
  1059. while other file sets are defined at startup time through the use of file 
  1060. globbing. See the TCL manual page for a definition of "glob"ing. The 
  1061. definition of the variable "globNecessary" in "procs.tcl" shows how to to 
  1062. this. 
  1063.  
  1064. Functions that use file sets operate on the "current" fileset, which is 
  1065. specified by the 'fileSet' variable. The current file set can also be 
  1066. switched by using  the "File Set" heirarchical menu. 
  1067.  
  1068.  
  1069. 5.02 includes a new Tcl proc 'addFileset', which allows a fileset to be 
  1070. created on the fly. This 
  1071. fileset remains usable until Alpha is restarted. It should be quite simple 
  1072. to use Tcl to make this new fileset permanent. A Tcl proc could also be 
  1073. written to create a heirarchical menus that has a submenu for each fileset, 
  1074. the items of each submenu being the files for that fileset. However, I'm 
  1075. not going to write everything... 
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090. =============================================================================
  1091. = Keyboard Macros
  1092. =============================================================================
  1093.  
  1094.  
  1095. Defining and Using Keyboard Macros ALPHA supports keyboard macros which 
  1096. record a sequence of keystrokes to be played back later w/ the function 
  1097. 'executeKeyboardMacro' (this function is also in the 'Utilities' menu) or 
  1098. written into a buffer by selecting 'Dump Macro' from the 'Utilities' menu. 
  1099. The dump function prompts you for a macro name, which must consist only of 
  1100. letters of the alphabet, digits, and '_'. 
  1101.  
  1102. These macro declarations can then be edited, loaded, and bound to 
  1103. keystrokes. Loading a macro or a binding is accomplished by hiliting the 
  1104. text and selecting the "Load Selection" item of the 'Customize' window. If 
  1105. no text is hilited, the entire window is loaded by the same command. 
  1106. Macros can be bound to keys in exactly the same manner as functions (see 
  1107. above). 
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127. =============================================================================
  1128. = Undo + Redo
  1129. =============================================================================
  1130.  
  1131.  
  1132. ALPHA supports unlimited undo and redo. This means that most changes can 
  1133. be undone, and then redone, at will. Bear in mind that once you create new 
  1134. modifications, all changes that you have undone but not redone are lost. 
  1135. Another point to bear in mind is that saving a buffer to disk currently 
  1136. flushes the undo buffer. 
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.  
  1149.  
  1150.  
  1151.  
  1152.  
  1153.  
  1154.  
  1155.  
  1156.  
  1157.  
  1158.  
  1159.  
  1160.  
  1161.  
  1162.  
  1163.  
  1164. =============================================================================
  1165. = Think 6.0
  1166. =============================================================================
  1167.  
  1168. Yes! Finally Think has support for external editors. To make this work, 
  1169. put an alias of Alpha (version 5.5 or later) in the "Tools" subdirectory 
  1170. of the directory the project manager is in, and name the alias "Editor". 
  1171. Secondly, check the "Use External Editor" button in the project manager's 
  1172. option dialog. Finally, check the "Always Check File Dates" button.
  1173.  
  1174. Any open window events will now be vectored to Alpha, and from within 
  1175. Alpha you can initiate compiles, disassembles, makes, etc. Errors are 
  1176. reported back to Alpha displayed in a window titled "Browser". The only 
  1177. useful things to do in the browser window are to select the error you 
  1178. want (by moving up and down w/ the arrow keys), and telling Alpha to 
  1179. display the error by hitting return or Enter on the correct line. 
  1180.  
  1181. Caveats and comments:
  1182.     1) This is all very shaky right now, I'm currently short of time.
  1183.     2) Think's event support isn't all there. In particular, I've 
  1184.        seen some bombs caused entirely by the project manager, and the 
  1185.        "Make" apple event doesn't appear to do anything.
  1186.     3) Think's debugger currently doesn't accept Apple Events telling it to 
  1187.        open a file and go to a specific line. This will change in the near 
  1188.        future. In the meantime, it is not possible to tell the debugger to 
  1189.        go to a specific line at all, when using an external editor. You CAN 
  1190.        go into think, select a file name from the project window (don't open 
  1191.        it) and go to the debugger from there. This gets the debugger to the 
  1192.        file you want, but not the correct line.
  1193.     4) Look in :Tcl:SystemCode:"think.tcl" and "browser.tcl" for the code 
  1194.        controlling much of the interactions between THINK and Alpha. If you 
  1195.        improve anything, please send it back to me.
  1196.  
  1197.  
  1198. For pre-6.0, after editing w/ Alpha hit the 'Use Disk' button from the 
  1199. 'Build' menu item to force Think to check modification times for a build. 
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.  
  1207.  
  1208.  
  1209.  
  1210.  
  1211.  
  1212.  
  1213.  
  1214.  
  1215.  
  1216.  
  1217.  
  1218.  
  1219.  
  1220.  
  1221.  
  1222.  
  1223. =============================================================================
  1224. = Rectangular Editing
  1225. =============================================================================
  1226.  
  1227.  
  1228. If the option key is pressed while the mouse is dragged,  a rectangular 
  1229. section of text is selected instead of the normal selection. This 
  1230. rectangular selection may extend over multiple lines, but contains only 
  1231. text between the column of the drag start and the column of the drag end. 
  1232. The drag cannot end on a column or row less than the start. This selection 
  1233. can be extended by option-shift-mouse, but not dragged further.
  1234.  
  1235. The rectangular selection can be deleted, copied, and pasted. This is very 
  1236. useful for tables and arrays, such as in LaTeX. Usually, the operation 
  1237. will be intuitive. However, if you use proportional fonts the selection 
  1238. may appear ragged. If some of the line contain tabs, the result may not be 
  1239. want you want. Converting tabs to spaces in the desired region before 
  1240. attempting rectangular selection usually fixes the problems. 
  1241.  
  1242. The most natural semantics of rectangular selection aren't obvious. I 
  1243. chose to implement it in a similar fashion to that of Microsoft Word. 
  1244. Preditor does it in another way, and has many bugs (and it's  commercial, 
  1245. hah!).
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260. =============================================================================
  1261. = Using LaTeX
  1262. =============================================================================
  1263.  
  1264.  
  1265. As I am starting to write papers on my Mac using OzTeX, Alpha may migrate 
  1266. increasingly into the realm of LaTeX users. For starters, LaTeX support 
  1267. includes:
  1268.  
  1269. • automatic word-wrapping.
  1270. • fill paragraph and fill region commands.
  1271. • support for changing paragraph definitions 
  1272.    so that a backslash limits paragraph extent.
  1273. • rectangular editing mode, useful for working
  1274.    with tables and arrays.
  1275. • title-bar section menu.
  1276. • suffix hook for .tex (see the section on suffix 
  1277.    hooks) that can automatically enable all this.
  1278.  
  1279. The only one of the above items that hasn't been explained is the title-bar 
  1280. section menu, which is specified by appropriate settings of 'funcExpr', 
  1281. 'funcPar', and the function 'winFuncTitle'.  For files ending in ".tex", 
  1282. the title-bar contains a box labeled "Sect".  Clicking on this box creates 
  1283. a popup menu containg all section definitions in the current file.  
  1284. Selecting one puts the cursor at the beginning of the section.  See the 
  1285. Popup Menus section and the startup files for more information.
  1286.  
  1287. In addition, distributions from 5.0 on include a ``latex.tcl'' file that 
  1288. has many useful latex'ing macros.  Finally, 
  1289. "public/Alpha/contrib/smart.tcl" on cs.rice.edu contains macros that 
  1290. implement smart quotes.  By default, this file is loaded when latex.tcl is 
  1291. loaded.
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300. =============================================================================
  1301. = The (Dreaded) Option Key
  1302. =============================================================================
  1303.  
  1304.  
  1305. ALPHA's default setup uses the command key like any other mac application. 
  1306. Problems arise in ALPHA's emulation of emacs key bindings. Emacs uses an 
  1307. escape key and a control key.  Alpha's default configuration is set up for 
  1308. Mac II's. Emacs's escape and control keys are emulated by the Mac's 
  1309. corresponding keys. For Mac+'s, however, the situation is much more 
  1310. complicated. They don't have an escape key, so the the backquote key, '`', 
  1311. must be used instead. This can be set up by uncommenting the appropriate 
  1312. line in the "AlphaBits.tcl" file. Also, Mac+'s don't have control keys, so 
  1313. the option key can be used instead.  However....
  1314.  
  1315. Using the option key isn't quite that simple. First, the option key is 
  1316. already used in two contexts. There may be other option bindings. Also, if 
  1317. the variable 'optionIsEscape' is set, the option key is treated as if it 
  1318. is an escape so as to allow single keystroke calls of Alpha functions. In 
  1319. order to use the option key as an escape key, this variable must be set to 
  1320. zero in the AlphaBits file. Also, all the relevant bindings must have 
  1321. their modifier strings changed from using 'z' to 'o'.
  1322.  
  1323. There are other problems. Several option combinations are "dead keys" 
  1324. (option-e, option-o....), they are used to create bizarre (sorry to y'all 
  1325. non-Amuricans) characters through multiple keystrokes. Alpha can fix this 
  1326. by overlaying the system 'KCHR' resource with a private modified resource. 
  1327. This happens at startup time if the "AlphaBits.tcl" file specifies a zero 
  1328. value for the variable 'noRemapOption'. Unfortunately, this is just a US 
  1329. version of the resource, it won't work "fur the non-Amuricans".
  1330.  
  1331.  
  1332.  
  1333.  
  1334.  
  1335.  
  1336.  
  1337.  
  1338.  
  1339.  
  1340.  
  1341. =============================================================================
  1342. = System Software 7.0
  1343. =============================================================================
  1344.  
  1345. Alpha is 32-bit clean and high-level event aware. 
  1346.  
  1347. Under 7.0, Alpha uses temporary memory to accommodate large files. This 
  1348. allows you to open multi-megabyte files even when Alpha's partition is set 
  1349. only at 512k, if the system has that much memory available. Note that 
  1350. using temporary memory makes that much memory unavailable to other 
  1351. applications. Contrary to all admonishments, Alpha does not unlock 
  1352. temporary memory across WaitNextEvent calls and may eventually use all the 
  1353. memory in your system. You can turn this feature off through 'tempMem'.
  1354.  
  1355. Note, however, that the clipboard is allocated by the system in Alpha's 
  1356. heap, and therefore cannot take advantage of temporary memory.
  1357.  
  1358.  
  1359.  
  1360.  
  1361.  
  1362.  
  1363.  
  1364.  
  1365.  
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378. =============================================================================
  1379. = Apple Events
  1380. =============================================================================
  1381.  
  1382. Alpha currently only supports only the four required high-level events 
  1383. (OpenApp, OpenDoc, PrintDoc, and QuitApp) and the DoScript ('dosc') 
  1384. event. Alpha accepts two types of parameters for DoScript: 
  1385.     typeChar    - Tcl text to be executed, and
  1386.     typeAlias    - FSSpec of file to be sourced.
  1387. Alpha returns the result of the last Tcl command executed. 
  1388.  
  1389. Alpha can also send 'dosc' Apple Events. See the 'dosc' command in the 
  1390. "Alpha Tcl Extensions" help file. 
  1391.  
  1392. And finally, Alpha supports Think's third-party editor interface, see the 
  1393. "Think 6.0" section for detail.
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416. =============================================================================
  1417. = MPW
  1418. =============================================================================
  1419.  
  1420. Alpha's 'dosc' capability (see the function "dosc") can be used to send 
  1421. events to MPW's ToolServer. Using about ten lines of C code and the ~40 
  1422. lines of Tcl code in 'mpw.tcl', I created a pseudo mpw shell (look under 
  1423. the "Misc" menu). This shell uses Alpha's 'dosc' function to package each 
  1424. shell command up into an Apple Event and send it to the ToolServer, which 
  1425. then evaluates the command and returns the result to be displayed in the 
  1426. shell. I'm rather new to Apple Events and the ToolServer, so there are 
  1427. probably a few rough edges. 
  1428.  
  1429. If anyone has extensive docs for ToolServer I'd appreciate looking at them. 
  1430. I only have the application because I am a beta tester for another product 
  1431. that supports ToolServer. I was given the application for the beta testing, 
  1432. but not any docs. And of course, I can *not* give away copies of 
  1433. ToolServer because it is a licensed Apple product.
  1434.  
  1435. Finally, Tom Moertel (thor@vivaldi.psu.edu) has written and provided a set 
  1436. of tools that make life easier while writing code in Alpha for the MPW 
  1437. environment. The tools make extensive use of Apple Events, so you must be 
  1438. using MPW 3.3a or greater. (Earlier versions cannot receive commands via 
  1439. Apple Events.) 
  1440.  
  1441.   With the MPW-Alpha package you can:
  1442.   
  1443.     o  Send TCL commands to Alpha from MPW
  1444.     o  Use MPW 411 from Alpha for instant access to programming help
  1445.     o  Automagically locate source code errors from your last MPW compile
  1446.     o  Use the MPW CDent tool to reformat (grind) C/C++ source code
  1447.        from within Alpha
  1448.  
  1449. This package is available via anonymous ftp from cs.rice.edu.
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.  
  1461.  
  1462.  
  1463.  
  1464.  
  1465.  
  1466. =============================================================================
  1467. = File Formats
  1468. =============================================================================
  1469.  
  1470.  
  1471. Alpha reads and writes files stored in three (or maybe four) different 
  1472. formats. The three main formats are mac (lines end with a carriage 
  1473. return), unix (lines end with linefeed), and IBM pc (lines end with both 
  1474. carriage return and linefeed. Typical, isn't it?).
  1475.  
  1476. Alpha will transparently read and write all three of these formats. You 
  1477. don't have to do anything special to use different formats, but the 
  1478. 'SaveAs...' dialog allows you to specify the format that a file is written 
  1479. in through the 'Format' button.
  1480.  
  1481. The fourth file format is just a modification of the ordinary mac format. 
  1482. Word processors such as Microsoft Word and MacWrite only put carriage 
  1483. returns at the end of paragraphs, so that they can wrap  the paragraphs on 
  1484. the fly. This is what is referred to as 'paragraph format' in the rest of 
  1485. the help text. Alpha does not transparently convert to and from this 
  1486. format because there are valid reasons why someone might want to edit a 
  1487. paragraph formatted file while not in paragraph mode. 
  1488.  
  1489. Therefore, when Alpha detects reads a paragraph-mode file, it asks the 
  1490. user whether or not to remap it. Files can be mapped back to paragraph 
  1491. mode by setting 'fillColumn' to a very large number and executing 
  1492. 'fillRegion' on the text.
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503. =============================================================================
  1504. = Printing
  1505. =============================================================================
  1506.  
  1507. The current window is printed through the "Page Setup..." and "Print..." 
  1508. File menu items. The variable 'suppressHeader' controls whether a header 
  1509. is printed on each page, 'leftMargin', 'topMargin', and 'bottomMargin' 
  1510. control margins on the printed page.
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540. =============================================================================
  1541. = Tips and other Miscellaneous Diversions...
  1542. =============================================================================
  1543.  
  1544.  
  1545. • When a window is "dirty" (has unsaved changes), a 
  1546.   diamond appears in the title bar and next to the
  1547.   corresponding item in the Windows menu.
  1548.  
  1549. • All dialogs that have editable text can use the Cut, 
  1550.   Copy, and Paste menu command equivalents.
  1551.  
  1552. • In all dialogs, non-editable controls can be selected 
  1553.   by typing Command-<first char of control>. If there 
  1554.   are no editable controls in the dialog, simply typing 
  1555.   the first letter of the desired control suffices.
  1556.  
  1557. • Dirty windows are marked with a diamond in the 
  1558.   window's title bar. The corresponding menu items in 
  1559.   the 'Window' menu will also have a diamond mark next 
  1560.   to it.
  1561.  
  1562. • Set the flag 'undoOn' to 0 in order to speed up long 
  1563.   replace-all and macro modifications.
  1564.  
  1565. • After a piece of text has been yank'd or paste'd, the 
  1566.   'mark' is set to the beginning of the new text and the
  1567.   selection is at the end. 'markHilite' will now hilite 
  1568.   the entire insertion. This is especially useful when
  1569.   moving code. Cut the code, insert at a new position,
  1570.   select the inserted text by selecting "Edit:Hilite", and 
  1571.   then use "Edit:Shift Left" and "Edit: Shift Right" to move
  1572.   the text to the proper indentation.
  1573.  
  1574.  
  1575.  
  1576.  
  1577. ============================================================================= 
  1578. = Variables 
  1579. ============================================================================= 
  1580.  
  1581. There are two different kinds of variables in the Alpha world. These are 
  1582. internal variables and Tcl variables. You can only directly access the 
  1583. latter. However, the internal variables can be modified by creating a Tcl 
  1584. variable of the same name and "binding" it to its internal counterpart via 
  1585. the 'shadowVar' command (See the "Alpha Tcl Extensions" file under the 
  1586. "Help" menu for 'shadowVar's syntax). The following is a listing of the 
  1587. internal variables that can be bound using 'shadowVar': 
  1588.  
  1589. autoSave       • If TRUE, buffers (except untitled buffers) are automatically
  1590.                  saved every 'changesLim' changes.
  1591. backDir           • Directory in which to store backup files.
  1592. backSuffix     • Suffix to append to backup files.
  1593. backup         • if TRUE, the default Tcl proc 'saveHook' makes a backup 
  1594.                  of a file before the data is written. The default backup scheme has 
  1595.                  extension "~".
  1596. blockCursor    • if true, Alpha uses a block cursor instead of a vertical 
  1597.                  line. 
  1598. bwWindows      • if true, Alpha will use 1-bit windows
  1599.                  even if color is available. This speeds
  1600.                  refresh quite a bit on slow color 
  1601.                  machines such as the IIsi.
  1602. changesLim     • number of changes to a window before 
  1603.                  garbage collection or autosave is done.
  1604. currFileSet    • name of currently selected file set.
  1605. defaultFont    • font to use on new windows and files 
  1606.                  which don't have associated font 
  1607.                  specification resources.
  1608. defHeight      • If 'fullScreen' set, this is default 
  1609.                  height in pixels.
  1610. defWidth       • If 'fullScreen' set, this is default 
  1611.                  width in pixels.
  1612. elecLBrace     • Electric 'C' left brace on.
  1613. elecRBrace     • Electric 'C' right brace on.
  1614. electricSemi   • Electric 'C' semicolon on.
  1615. fillColumn     • Number of columns use as limit for
  1616.                  "fill" routines. See 'leftFillColumn'
  1617. fontSaving     • if '-1', Alpha never saves font info,
  1618.                  if '1', Alpha always saves font info,
  1619.                  '0', Alpha saves font info if the font
  1620.                  or size is different than the default.
  1621. fontSize       • Default size of fonts used to display 
  1622.                  files.
  1623. fullNames      • Windows display pathnames instead of 
  1624.                  mere file names.
  1625. fullScreen     • If on, all windows are start in the 
  1626.                  same place, and have the dimension 
  1627.                  specified by 'defHeight' and 
  1628.                  'defWidth'.
  1629. funcPar        • Used in defining the "Func" title-bar menu, see Alpha 
  1630.                    help.
  1631. funcExpr       • Set to the regular expression that 
  1632.                  ALPHA uses to find function 
  1633.                  declarations.
  1634. funcTitle      • Text to put in title-bar menu header.
  1635.                  See the Popup-Menus section for more
  1636.                  information.
  1637. horScrollBar   • If set, use horizontal scrollbar.
  1638. includePath    • A list of the path-names of the 
  1639.                  directories to search for include 
  1640.                  files, separated by semi-colons, such
  1641.                  as:
  1642.                    "Disk:C:edit;Disk:C:THINK C:include;"
  1643.                  The current directory can be included
  1644.                  by using consecutive semi-colons as:
  1645.                  "Disk:C:edit;Disk:C:THINK C:inc;;"
  1646. indentOnCR     • Auto-indent on carriage return.
  1647. leftFillColumn • Number of blanks left at beginning of 
  1648.                  lines by 'fill' routines. 
  1649. markLabel       • If a window is opened through either 'edit' or 'fileMenu' 
  1650.                  and the '-m' option was set, this string is used as the label of the 
  1651.                  marks menu.
  1652. markSorting       • Controls the order in which marks are saved into a file. 
  1653.                  '0' means the order in which they are defined, '1' means file 
  1654.                  order, and '2' means alphabetical order.
  1655. moveInsertion  • if true, 'pageBack' and 'pageForward'
  1656.                  move the insertion point
  1657. numWinsToTile  • specifies the number of windows tile
  1658.                  commands should affect.
  1659. openAllFIles   • if true, or it option key down, files 
  1660.                  of all types are openable, not just
  1661.                  'TEXT'.
  1662. optionIsMeta   • If set, the key combination with escape
  1663.                  is used instead of the option key
  1664.                  combination. Note that some 
  1665.                  combinations with option chars are
  1666.                  dead keys.
  1667. paraColumn     • Alpha automatically wraps files
  1668.                 that contains lines longer than this. 
  1669. posActivate    • If true, then merely moving the mouse
  1670.                  over a window activates. For those
  1671.                  X11-twm lovers.
  1672. powerThumb       • If true, vertical scrollbars have power thumbs.
  1673. protoFile      • name of file to dump prototypes into.
  1674. replaceStr       • Text for the search and replace functions.
  1675. savedState       • set to either "mpw", "think", or "none" depending on how 
  1676.                  much information you wish Alpha to save in the resource fork of the 
  1677.                  files you edit. See the "Files" section of this file for more 
  1678.                  information.
  1679. searchStr       • Text for the search and replace functions.
  1680. showRowCol     • if set, row and col are continuously
  1681.                  displayed in the title bar. 
  1682. showMenuHeads  • If set, the function and mark menus can 
  1683.                  be selected from the title bar.
  1684. intelCutPaste  • If enabled, cut and paste routines try to 
  1685.                  intelligently treat surrounding white space.
  1686. sortColumn     • column to use for sort routine.
  1687. sortedIsDefault• if set, sorted is the default for 
  1688.                  function and section menus.
  1689. suppressHeader • Suppress header on printed pages.
  1690. tabSize        • Default number of characters per tab.
  1691. tagFile        • complete path-name of tag file
  1692. tempMem        • if zero, Alpha will not use temporary
  1693.                  memory.
  1694. undoOn         • used to turn undo on and off. When undo
  1695.                  is turned off, all undo info is lost.
  1696.                  Useful when doing global replaces, etc.
  1697. wordBreak       • Regular expression used to defines words for all internal 
  1698.                  operations. 
  1699. wordBreakPreface • Prepended to 'wordBreak' when looking backwards for a 
  1700.                  word. See the "Word Break" section of this file for more 
  1701.                  information.
  1702. wordWrap       • if true, lines exceeding 'fillColumn'
  1703.                  in length are automatically wrapped
  1704.                  during normal text insertion (typing)
  1705.  
  1706.  
  1707.  
  1708. ================================================================================
  1709. = Spellchecking
  1710. ================================================================================
  1711.  
  1712. Alpha has the capability to interact with the spell-check 'Excalibur', 
  1713. written by Robert Gottshall and Rick Zaccone.  The menu item 'Spellcheck 
  1714. Window' is always available in either the menu w/ Excalibur's icon, or 
  1715. under the Latex menu (with the OzTex menu).  Selecting this item will start 
  1716. up Excalibur and send an OpenDoc event describing the current window.  For 
  1717. version 1.4 and earlier, if Alpha has to launch Excalibur you will need to 
  1718. dismiss Excalibur's opening dialog by hitting the Cancel button.  
  1719. Subsequent selections of the menu item will switch right into Excalibur 
  1720. with the correct file displayed.  In future versions, this will become even 
  1721. more automatic.
  1722.  
  1723. Excalibur is free, but not in the public domain.  It can be obtained from 
  1724. all the usual Internet ftp sites, as well as cs.rice.edu under 
  1725. public/Alpha.
  1726.  
  1727.  
  1728.  
  1729.  
  1730.  
  1731.  
  1732.  
  1733.  
  1734.  
  1735.  
  1736.  
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746. ===========================================================================
  1747. = INTERNATIONAL USERS
  1748. ===========================================================================
  1749. Remember, if you want to use anything other than the US KCHR resource 
  1750. (si vous voulez ecrire en francais, par exemple), change the line:
  1751.  
  1752.  init 0 2
  1753.  
  1754. of :Tcl:SystemCode:AlphaBits.tcl to
  1755.  
  1756.  init1 2
  1757.  
  1758. and restart. Alpha will now use your native KCHR, but the key binding labels
  1759. (such as F1 etc.) may not work, and option-e etc. are now "dead keys". 
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789. ===========================================================================
  1790. = Drag and Drop Editing
  1791. ===========================================================================
  1792.  
  1793. Alpha supports drag and drop cut, copy, clear, and paste. To use this 
  1794. feature, select some text, then move the cursor over the selected text. 
  1795. The cursor should then turn into an open hand. Mouse down, and move the 
  1796. cursor to the place you wish to paste the text. When the mouse is 
  1797. released, the hilited text is moved to the new location.
  1798.  
  1799. Option-mouse does a "copy" instead. Dragging the cursor from the selected 
  1800. text off the edge of the window will clear it.
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.